<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>Ant-contrib Server Tasks</title>
  </head>

  <body>
    <h1>Ant-Contrib Server Tasks</h1>

    <p>The following tasks exist for running Ant server on one machine, and
       calling that server from another (or possibly the same) machine, to
       execute tasks.</p>


    <hr width="100%" />

    <h1>AntServer</h1>

    <p>
        Starts an ANT server in current process.  This server will wait for
        client connections, and when received, it will execute the commands
        that the client has sent.  NOTE:  This is a blocking call, and this
        task will not return until someone sends the server a shutdown command.
    </p>

    <h2>Parameters</h2>

    <table border="1" cellpadding="2" cellspacing="0">
      <tr>
        <th>Attribute</th>
        <th>Description</th>
        <th>Required</th>
      </tr>
      <tr>
        <td valign="top">port</td>
        <td valign="top">The port on which the server will listen.</td>
        <td align="center" valign="top">No. Defaults to 17000</td>
      </tr>
    </table>

    <h2>Example:</h2>

    <pre>
    <code>
        &lt;antserver port="12345" /&gt;
    </code>
    </pre>


    <h1>RemoteAnt</h1>

    <p>
        Sends command requests to a running instance of an AntServer which
        was started using the &lt;antserver&gt; task.
        These commands are executed in the space of the server, and therefore
        have no access to any variables or references in the currently executing
        project.
    </p>

    <h2>Parameters</h2>

    <table border="1" cellpadding="2" cellspacing="0">
      <tr>
        <th>Attribute</th>
        <th>Description</th>
        <th>Required</th>
      </tr>
      <tr>
        <td valign="top">machine</td>
        <td valign="top">The machine name on which the server is running.</td>
        <td align="center" valign="top">No. Defaults to "localhost"</td>
      </tr>
      <tr>
        <td valign="top">port</td>
        <td valign="top">The port on which the server is listening.</td>
        <td align="center" valign="top">No. Defaults to 17000</td>
      </tr>
      <tr>
        <td valign="top">persistant</td>
        <td valign="top">Should we execute all commands, regardless of whether
            or not one of them fails.  If false, as soon as a failure is encountered,
            we will stop execution.</td>
        <td align="center" valign="top">No. Defaults to false</td>
      </tr>
      <tr>
        <td valign="top">failonerror</td>
        <td valign="top">If any of the sent commands encounters a build failure on
            the server, should we fail this task.</td>
        <td align="center" valign="top">No. Defaults to true.</td>
      </tr>
    </table>

    <h2>Parameters Specified as Nested Elements</h2>

    <p>
        The commands to send are represented as nested elements as described
        below
    </p>


    <h3>runtarget</h3>

    <p>Runs a target which is contained in the same buildfile where the
       &lt;antserver&gt; task was called.  This element may contain nested
       &lt;property&gt; elements for sending parameters to the target, and
       nested &lt;reference&gt; elements for sending references to the target.</p>

    <h4>Parameters</h4>
    <table border="1" cellpadding="2" cellspacing="0">
      <tr>
        <th>Attribute</th>
        <th>Description</th>
        <th>Required</th>
      </tr>
      <tr>
        <td valign="top">target</td>
        <td valign="top">The name of the target to run.</td>
        <td align="center" valign="top">Yes.</td>
      </tr>
    </table>

    <h3>runant</h3>

    <p>Runs a target in an arbitrary buildfile on the machine where the
       &lt;antserver&gt; task was called.  If a relative pathname is given,
       then the path of the buildfile is relative to the base directory of
       the project where the &lt;antserver&gt; task was called.  This element
       may contain nested &lt;property&gt; elements for sending text parameters
       to the target, and nested &lt;reference&gt; elements for sending references
       to the target.</p>

    <h4>Parameters</h4>
    <table border="1" cellpadding="2" cellspacing="0">
      <tr>
        <th>Attribute</th>
        <th>Description</th>
        <th>Required</th>
      </tr>
      <tr>
        <td valign="top">antfile</td>
        <td valign="top">The path of the ant file to run (if relative, then
            the filename is computed relative to the buildfile of the server
            task's base directory</td>
        <td align="center" valign="top">No. Defaults to "build.xml" in the
            directory where the buildfile is to execute (specified by the dir
            attribute)</td>
      </tr>
      <tr>
        <td valign="top">target</td>
        <td valign="top">The name of the target to run.</td>
        <td align="center" valign="top">No.  Defaults to the default target of
            the specified antfile.</td>
      </tr>
      <tr>
        <td valign="top">dir</td>
        <td valign="top">the directory to use as a basedir for the new Ant project. Defaults to
            the server project's basedir, unless inheritall has been set to false, in which
            case it doesn't have a default value. This will override the basedir setting of
            the called project.</td>
        <td align="center" valign="top">No.</td>
      </tr>
      <tr>
        <td valign="top">inheritall</td>
        <td valign="top">Should the target task inherit all of
           the server's properties.  This is equivalent to the flag of
           the same name on the &lt;ant&gt; task.</td>
        <td align="center" valign="top">No. Defaults to false</td>
      </tr>
      <tr>
        <td valign="top">inheritrefs</td>
        <td valign="top">Should the target task inherit all of
           the server's references.  This is equivalent to the flag of
           the same name on the &lt;ant&gt; task.</td>
        <td align="center" valign="top">No. Defaults to false</td>
      </tr>
    </table>


    <h3>shutdown</h3>

    <p>Instructs the &lt;antserver&gt; task to shut itself down.  Control
       will return to the ANT engine and will procede as necessary in the
       server's buildfile.</p>


    <h2>Example:</h2>

    <pre>
    <code>
        &lt;remoteant machine="localhost" port="12345"&gt;
            &lt;runtarget target="execute.build"&gt;
               &lt;property name="build.type" value="full" /&gt;
            &lt;/runtarget&gt;
            &lt;runant dir="tests" target="build.tests"&gt;
               &lt;property name="build.type" value="full" /&gt;
               &lt;reference refid="my.ref" torefid="inherited.ref" /&gt;
            &lt;/runtarget&gt;
        &lt;/remoteant&gt;
    </code>
    </pre>


    <p>
    would be the equivalent of running the following directly on
    the server machine, from within the same buildfile where the
    &lt;antserver&gt; task was run
    </p>


    <pre>
    <code>
        &lt;antcall target="execute.build"&gt;
           &lt;param name="build.type" value="full" /&gt;
        &lt;/antcall&gt;
        &lt;ant dir="tests"&gt;
           &lt;property name="build.type" value="full" /&gt;
           &lt;reference refid="my.ref" torefid="inherited.ref" /&gt;
        &lt;/antcall&gt;
    </code>
    </pre>

    <h3>sendfile</h3>

    <p>Sends a file from the client to the server</p>

    <h4>Parameters</h4>
    <table border="1" cellpadding="2" cellspacing="0">
      <tr>
        <th>Attribute</th>
        <th>Description</th>
        <th>Required</th>
      </tr>
      <tr>
        <td valign="top">file</td>
        <td valign="top">The path of the file to send.</td>
        <td align="center" valign="top">Yes.</td>
      </tr>
      <tr>
        <td valign="top">tofile</td>
        <td valign="top">The filename where the file is to be stored
           on the server, if a relative path, then it is stored relative
           to the server project's base directory.</td>
        <td align="center" valign="top">No. If todir is specified</td>
      </tr>
      <tr>
        <td valign="top">tofile</td>
        <td valign="top">The directory where the file is to be stored
           on the server, if a relative path, then it is stored relative
           to the server project's base directory.  The name of the file
           will be the same name as the source file</td>
        <td align="center" valign="top">No. If tofile is specified</td>
      </tr>
    </table>

    <hr>
    <p align="center">Copyright &copy; 2003 Ant-Contrib Project. All
    rights Reserved.</p>

  </body>
</html>